Summary and Howto

The application needs to call NcApiInit() once.
List of UART interrupt service routines that needs to be in place:

CTS edging lower: call NcApiCallbackCtsActive()
RX (optinally also RT): call NcApiRxDataReceived()

The application needs to implement these methods:

It can chose to be notified for certain message types through the instance of NcApiRxHandlers.
A complete example is available following the sequence diagrams.

Startup

The application merely needs to call NcApiInit() once.

Sending a command to a node

The application merely needs to call NcApiSendAcknowledged(), which handles serialization of the packet and enqueues it.

Handling of UART CTS interrupts

The application needs to set up an interrupt service routine for UART CTS interrupts when the CTS edges low, and forward the call to NcApiCallbackCtsActive(). If there is one pending enqueued message it will call NcApiTxData(). When the entire message has been delivered to the UART, only then will it call NcApiMessageWrittenCallback().

Handling of UART RX Data

The application needs to set up an interrupt service routine for UART RX and RT (receive time-out) interrupts, and forward any data from the UART FIFO to NcApiRxDataReceived(). When a complete message has been received, the application will be notified via optional callbacks defined in NcApiRxHandlers.

//Copyright (c) 2015, NeoCortec A/S
//All rights reserved.
//
//Redistribution and use in source and binary forms, with or without
//modification, are permitted provided that the following conditions are met:
//
//1. Redistributions of source code must retain the above copyright notice,
//   this list of conditions and the following disclaimer.
//
//2. Redistributions in binary form must reproduce the above copyright notice,
//   this list of conditions and the following disclaimer in the documentation
//   and/or other materials provided with the distribution.
//
//3. Neither the name of the copyright holder nor the names of its contributors
//   may be used to endorse or promote products derived from this software
//   without specific prior written permission.
//
//THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
//AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
//IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
//DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
//FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
//DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
//SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
//CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
//OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
//OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

// This example configures one instance of NcApi.
// It shows a bare minimum implementation of what is required in order to receive and send messages.
// It is recommened to walk through ExampleSetupNcApi() and ExampleSendAcknowledged() defined at the end of this file.

#include "NcApi.h"

// Global declarations expected by NcApi
tNcApi g_ncApi[1];
uint8_t g_numberOfNcApis = 1;
tNcApiRxHandlers g_ncRxHandlers;

// Global functions expected by NcApi
void NcApiWriteData(uint8_t n, uint8_t * finalMsg, uint8_t finalMsgLength)
{
    // Write to particular UART indexed by n
}
void NcApiWriteCallback(uint8_t n, void * callbackToken, uint8_t * finalMsg, uint8_t finalMsgLength)
{
}

// Handle CTS and RX interrupts
void ExamplePassthroughCts()
{
    NcApiCallbackCtsActive(0);
}
void ExamplePassthroughRx(uint8_t byte)
{
    NcApiRxDataReceived(0, byte);
}

// Sample implementation of generic message received handler merely providing the bytes.
// Always called before any of the strongly typed message handlers are called.
void ExampleReadCallback(uint8_t n, uint8_t * msg, uint8_t msgLength)
{
    uint16_t i;
    printf("Raw UART data received: ");
    for (i=0; i<msgLength; i++)
        printf( "%02x ", msg[i] );
    printf("\r\n");
}
void ExampleHostAckCallback(uint8_t n, tNcApiHostAck * p)
{
    printf( "My previous package to node node %04x was successfully delivered\r\n", p->originId );
}
void ExampleHostNAckCallback(uint8_t n, tNcApiHostAck * p)
{
    printf( "My previous package to node node %04x was not delivered\r\n", p->originId );
}
void ExampleHostDataCallback(uint8_t n, tNcApiHostData * p)
{
    printf
    (
        "I have received %d bytes from node %04x. They are %dms old\r\n",
        p->payloadLength,
        p->originId,
        p->packageAge * 125
    );
}
void ExampleHostDataHapaCallback(uint8_t n, tNcApiHostDataHapa * p)
{
    printf
    (
        "I have received %d bytes from node %04x. They are %dms old\r\n",
        p->payloadLength,
        p->originId,
        ((double)p->packageAge) / 524.288
    );
}

// Sample implementation of how to send one message
void ExampleSendAcknowledged(uint16_t destNodeId, uint8_t port, uint8_t * payload, uint8_t payloadLen)
{
    tNcApiSendParams args;
    args.destNodeId = destNodeId;
    args.destPort = port;
    args.payload = payload;
    args.payloadLength = payloadLen;
    args.callbackToken = &g_ncApi;
    NcApiSendAcknowledged( 0, &args );
}

// Sample implementation of how to setup global rx-handlers and initialize NcApi.
void ExampleSetupNcApi()
{
    tNcApiRxHandlers * rxHandlers = &g_ncRxHandlers;
    memset( rxHandlers, 0, sizeof(tNcApiRxHandlers));
    rxHandlers->pfnReadCallback = ExampleReadCallback;
    rxHandlers->pfnHostAckCallback = ExampleHostAckCallback;
    rxHandlers->pfnHostNAckCallback = ExampleHostNAckCallback;
    rxHandlers->pfnHostDataCallback = ExampleHostDataCallback;
    rxHandlers->pfnHostDataHapaCallback = ExampleHostDataHapaCallback;
    NcApiInit();
}